前面兩篇把名片系統做起來了：手機拍一張、OCR 認出來、人確認、存進資料庫。可是名片躺在名片系統裡，跟躺在抽屜裡差不了多少。真正要用它的地方是 ERP：報價、開單、寄信，全部從 ERPNext 裡的一筆客戶資料開始。

所以這一篇只做一件事：手機拍完名片，那張名片資料自動出現在 ERPNext 裡。不用人再打一次字，不用匯出匯入，不用記得去同步。

三個決定先講清楚：不分私人名片還是公司名片，全部進 ERP。每一張名片都變成一筆潛在客戶 Lead。第一版只建不改不刪：名片改了不回寫，ERP 那邊刪了也不管。

規則：先決定「什麼東西一定進、什麼東西一定不做」，再動手接，接完才來吵這些會沒完沒了。

一律當潛在客戶

ERPNext 把「人」分成兩層。潛在客戶 (Lead) 是還沒開過單的對象，一筆 Lead 就是一個人，自己帶公司名、職稱、email、手機。客戶 (Customer) 是已經成交，有開訂單，會有會計主檔，帶應收科目、信用額度、價目表，人的資料要另外掛在聯絡人 Contact 底下。

一張剛掃進來的名片，照定義就是 Lead。它連要不要做生意都還不知道，硬塞成 Customer 只會讓會計主檔長滿沒交易過的公司。所以名片系統只負責建 Lead；哪一天真的成交，業務在 ERPNext 裡按一下「建立客戶」，Contact 和地址都是 ERPNext 自己生出來的，名片系統不用管。

規則：接兩個系統時，先問對方的資料模型怎麼分層，把自己的東西放進最低那一層，往上升的動作留給人。

欄位怎麼對

名片系統一張卡有姓名、稱謂、公司、職稱、電話清單、email 清單、地址、國家、網站。Lead 那邊有 first_name、company_name、job_title、mobile_no、phone、phone_ext、fax、email_id、website、country。

中文姓名整串放進 first_name，不硬拆姓和名。電話照名片系統的標籤分：mobile 進手機欄、office 進電話欄、ext 進分機、fax 進傳真，同一類第二支以後和認不出標籤的，全部寫進 Lead 底下的一則筆記。email 第一個進 email_id，其餘也進筆記。地址不另建 Address 文件，同樣進筆記，因為 Lead 本身沒有地址列，而 Address 又逼你填城市和國家，名片常常沒有。

國家欄位是 ERPNext 的連結欄，填的字一定要在國家主檔裡存在，所以做了一張對照表：台灣、臺灣、Taiwan、中華民國都對到 Taiwan，香港對 Hong Kong。對不上的不填，原文寫進筆記，不猜。

去除重複：靠一個自訂欄位：在 Lead 上加 namecard_id，存名片系統那張卡的 id。送之前先用這個 id 查一次，查得到就不再建。

規則：兩邊欄位對不上的，不要硬塞也不要丟掉，全部寫進筆記，讓人在 ERP 裡看得到原文。

Claude code 原本計畫很笨：跑一支腳本，每分鐘去名片系統檢查，只要發現新的名片，就呼叫 ERPNext 的 REST API 建 Lead

我開始疏忽掉，讓他跑，檢查時覺得不對：有新增名片，就直接送進 ERP，幹嘛要每分鐘檢查？這做法也太笨了吧？！所以，AI提出的方案，要想一想，檢查一下，別以為他真的是天才。
他還很認真地說：「有新名片進來，就送到 ERP」是名片系統自己的事，不該靠外面一台機器每分鐘來問一次。 ------ 哪你為甚麼一開始沒想到？

告訴 claude：

改成「有新名片進來，就送到 ERPNext」，同步住在名片系統本身，不靠外面排程：
- POST /cards 成功時，同一筆交易往 erp_outbox 插一列 pending，20 秒後到期（手機是先建卡再傳圖，讓正面圖先到）
- API 程序內開背景 worker，每 10 秒撈到期的列：先用 namecard_id 查 ERP（既有的 17 張會命中，不重建），
  沒有才建 Lead；有正面圖就上傳並寫進頭像欄位；成功標 sent 並寫稽核紀錄
- 正面圖晚到：上傳圖片時若該卡已 sent 但還沒圖，把它叫回來補圖
- 失敗：attempts+1，等待 10s×2^n 最長 15 分鐘，最多 20 次，之後留 error 等管理員 requeue；圖片失敗不算失敗
- admin 端點：status / requeue/{card_id} / enqueue-missing
- 設定走 .env 的 ERP_*，三者皆有才啟用；程式與紀錄不得印 key/secret
- 控制台那支輪詢腳本降為手動補跑工具；直連資料庫的權宜之計還掉

新版本是在名片系統裡面，把名片存檔的那一筆交易，同時往一張佇列表 erp_outbox 插一列，狀態是待送。然後名片系統的 API 程序裡開一個背景工作，每 10 秒撈到期的列，建 Lead、上傳正面照片、寫稽核紀錄，成功就標成已送。

有兩個細節是輪詢版學來的。手機 App 是先建卡再傳照片，所以佇列那一列刻意延遲 20 秒才到期，讓正面照片先到；照片如果更晚才來，上傳照片的那一步會把已送出但還沒有照片的列叫回來補。失敗的列不會丟：等待時間一次比一次長，上限 15 分鐘，最多重試 20 次，之後留在那裡等管理員按一下重送。

控制台那支輪詢腳本降級成手動補跑工具，直連資料庫那條權宜之計就此還掉。名片系統這邊 claude 施工，486 條測試全綠才部署。

規則：同步這種事要住在資料產生的那一邊，用佇列而不是輪詢，失敗要看得到、重試要有上限。

新版部署到名片系統那台機器：重建 API 容器、跑資料庫遷移、看到背景工作啟動的訊息。塞一張合成名片進去，30 秒內 ERPNext 出現一筆 Lead，連照片都掛上了。17 張既有名片全部排進佇列，全部標成已送，ERP 的 Lead 數量維持 17 沒有重建。驗收全過。

ERPNext 裡面的 CRM

名片進去之後，去 ERPNext 找它，找不到。ERPNext v16 的首頁是一格一格的模組圖示，沒有左側選單，而且格子裡沒有 CRM。查了半天，權限、工作區、模組封鎖全部正常，最後發現是首頁圖示表裡 CRM 那一筆被標成隱藏，ERPNext 出貨就這樣，大概是想把人導去它另一個獨立的 CRM 產品。把隱藏拿掉，格子就出現了。( 這一段是叫 claude 做的 )

ERPNext v16 的首頁是一格一格的模組圖示，沒有左側選單；「客戶關係管理」那一格預設是隱藏，隱藏要拿掉才會出現的：

點進客戶關係管理，左側才有選單，選潛在客戶，名片來的那些用「來源等於名片」就篩得出來。點開一筆：左上角是名片正面照片，姓名、公司、職稱、手機、電話、傳真、email、國家在主表；地址、其他電話、原始國家名、名片是誰拍的、有沒有共享，全部在底下那一則筆記裡。

來試一下：

手機拍張名片：(抓螢幕的，省得要塗掉個資。)，過程就不重述。

到客戶關係管理，潛在客戶清單，最上面那筆是剛用手機拍進去的測試名片

點開一筆：右上角是名片正面照片，姓名、職稱、email、手機、電話、分機、組織都在主表；「名片 ID」就是去重鍵，主導擁有者是同步用的專用帳號

同一筆的筆記分頁：地址、對不上欄位的東西、名片是誰拍的、有沒有共享，全部留在這裡，人看得到原文

規則：資料進去了還要人找得到，找不到就等於沒進去；介面上少一個圖示，先查它是不是被藏起來，再查權限。

到這裡，手機拍一張名片，30 秒內 ERPNext 裡就多一筆潛在客戶，照片、電話、筆記都在，不用人再打一次字。

明天：讓 AI 寫信給客人。